<!-- HTML header for doxygen 1.13.2-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.13.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>yyjson: Building and testing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
<link href="yyjson-style.css" rel="stylesheet" type="text/css"/>
<!-- css awesome -->
<script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
    DoxygenAwesomeDarkModeToggle.init()
</script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname"><a href="index.html">yyjson</a><span id="projectnumber">&#160;0.12.0</span>
   </div>
   <div id="projectbrief">A high performance C JSON library.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.13.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search',true);
  $(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('building-and-testing.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Building and testing</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>There are several ways to integrate this library into your project: source code, package manager, and CMake.</p>
<h1><a class="anchor" id="source-code"></a>
Source code</h1>
<p>This library aims to provide a cross-platform JSON library, so it is written in ANSI C (actually C99, but compatible with strict C89). You can copy <code><a class="el" href="yyjson_8h.html">yyjson.h</a></code> and <code>yyjson.c</code> to your project and start using it without any configuration.</p>
<p>The library has been tested with <code>gcc</code>, <code>clang</code>, <code>msvc</code>, <code>tcc</code> compilers and <code>x86</code>, <code>arm</code>, <code>ppc</code>, <code>riscv</code>, <code>s390x</code> architectures in <a href="https://github.com/ibireme/yyjson/actions">Github CI</a>. Please <a href="https://github.com/ibireme/yyjson/issues/new?template=bug_report.md">report a bug</a> if you encounter any compilation issues.</p>
<p>The library has all features enabled by default, but you can trim out some of them by adding compile-time options. For example, you can disable the JSON writer to reduce the binary size when you don't need serialization, or disable comments support to improve parsing performance. See <code>Compile-time Options</code> for details.</p>
<h1><a class="anchor" id="package-manager"></a>
Package manager</h1>
<p>You can use some popular package managers like <code>vcpkg</code>, <code>conan</code>, and <code>xmake</code> to download and install yyjson. The yyjson package in these package managers is kept up to date by community contributors. If the version is out of date, please create an issue or pull request on their repository.</p>
<h2><a class="anchor" id="use-vcpkg"></a>
Use vcpkg</h2>
<p>You can build and install yyjson using <a href="https://github.com/Microsoft/vcpkg/">vcpkg</a> dependency manager:</p>
<div class="fragment"><div class="line">git clone https://github.com/Microsoft/vcpkg.git</div>
<div class="line">cd vcpkg</div>
<div class="line">./bootstrap-vcpkg.sh  # ./bootstrap-vcpkg.bat for Powershell</div>
<div class="line">./vcpkg integrate install</div>
<div class="line">./vcpkg install yyjson</div>
</div><!-- fragment --><p>If the version is out of date, please <a href="https://github.com/Microsoft/vcpkg">create an issue or pull request</a> on the vcpkg repository.</p>
<h1><a class="anchor" id="cmake"></a>
CMake</h1>
<h2><a class="anchor" id="use-cmake-to-build-the-library"></a>
Use CMake to build the library</h2>
<p>Clone the repository and create build directory: </p><div class="fragment"><div class="line">git clone https://github.com/ibireme/yyjson.git</div>
<div class="line">cmake -E make_directory build; cd build</div>
</div><!-- fragment --><p>Build static library: </p><div class="fragment"><div class="line">cmake .. </div>
<div class="line">cmake --build .</div>
</div><!-- fragment --><p>Build shared library: </p><div class="fragment"><div class="line">cmake .. -DBUILD_SHARED_LIBS=ON</div>
<div class="line">cmake --build .</div>
</div><!-- fragment --><p>Supported CMake options (default OFF):</p>
<ul>
<li><code>-DYYJSON_BUILD_TESTS=ON</code> Build all tests.</li>
<li><code>-DYYJSON_BUILD_FUZZER=ON</code> Build fuzzer with LibFuzzing.</li>
<li><code>-DYYJSON_BUILD_MISC=ON</code> Build misc.</li>
<li><code>-DYYJSON_BUILD_DOC=ON</code> Build documentation with doxygen.</li>
<li><code>-DYYJSON_ENABLE_COVERAGE=ON</code> Enable code coverage for tests.</li>
<li><code>-DYYJSON_ENABLE_VALGRIND=ON</code> Enable valgrind memory checker for tests.</li>
<li><code>-DYYJSON_ENABLE_SANITIZE=ON</code> Enable sanitizer for tests.</li>
<li><code>-DYYJSON_ENABLE_FASTMATH=ON</code> Enable fast-math for tests.</li>
<li><code>-DYYJSON_FORCE_32_BIT=ON</code> Force 32-bit for tests (gcc/clang/icc).</li>
<li><code>-DYYJSON_DISABLE_READER=ON</code> Disable JSON reader if you don't need it.</li>
<li><code>-DYYJSON_DISABLE_WRITER=ON</code> Disable JSON writer if you don't need it.</li>
<li><code>-DYYJSON_DISABLE_INCR_READER=ON</code> Disable incremental reader if you don't need it.</li>
<li><code>-DYYJSON_DISABLE_UTILS=ON</code> Disable JSON Pointer, JSON Patch and JSON Merge Patch.</li>
<li><code>-DYYJSON_DISABLE_FAST_FP_CONV=ON</code> Disable builtin fast floating-pointer conversion.</li>
<li><code>-DYYJSON_DISABLE_NON_STANDARD=ON</code> Disable non-standard JSON support at compile-time.</li>
<li><code>-DYYJSON_DISABLE_UTF8_VALIDATION=ON</code> Disable UTF-8 validation at compile-time.</li>
<li><code>-DYYJSON_DISABLE_UNALIGNED_MEMORY_ACCESS=ON</code> Disable unaligned memory access support at compile-time.</li>
</ul>
<h2><a class="anchor" id="use-cmake-as-a-dependency"></a>
Use CMake as a dependency</h2>
<p>You can download and unzip yyjson to your project directory and link it in your <code>CMakeLists.txt</code> file: </p><div class="fragment"><div class="line"># Add some options (optional)</div>
<div class="line">set(YYJSON_DISABLE_NON_STANDARD ON CACHE INTERNAL &quot;&quot;)</div>
<div class="line"> </div>
<div class="line"># Add the `yyjson` subdirectory</div>
<div class="line">add_subdirectory(vendor/yyjson)</div>
<div class="line"> </div>
<div class="line"># Link yyjson to your target</div>
<div class="line">target_link_libraries(your_target PRIVATE yyjson)</div>
</div><!-- fragment --><p>If your CMake version is higher than 3.11, you can use the following code to let CMake automatically download it: </p><div class="fragment"><div class="line">include(FetchContent)</div>
<div class="line"> </div>
<div class="line"># Let CMake download yyjson</div>
<div class="line">FetchContent_Declare(</div>
<div class="line">    yyjson</div>
<div class="line">    GIT_REPOSITORY https://github.com/ibireme/yyjson.git</div>
<div class="line">    GIT_TAG master # master, or version number, e.g. 0.6.0</div>
<div class="line">)</div>
<div class="line">FetchContent_GetProperties(yyjson)</div>
<div class="line">if(NOT yyjson_POPULATED)</div>
<div class="line">  FetchContent_Populate(yyjson)</div>
<div class="line">  add_subdirectory(${yyjson_SOURCE_DIR} ${yyjson_BINARY_DIR} EXCLUDE_FROM_ALL)</div>
<div class="line">endif()</div>
<div class="line"> </div>
<div class="line"># Link yyjson to your target</div>
<div class="line">target_link_libraries(your_target PRIVATE yyjson)</div>
</div><!-- fragment --><h2><a class="anchor" id="use-cmake-to-generate-project"></a>
Use CMake to generate project</h2>
<p>If you want to build or debug yyjson with another compiler or IDE, try these commands: </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line"> </div>
<div class="line"># Clang for Linux/Unix:</div>
<div class="line">cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++</div>
<div class="line"> </div>
<div class="line"># Intel ICC for Linux/Unix:</div>
<div class="line">cmake .. -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc</div>
<div class="line"> </div>
<div class="line"># Other version of GCC:</div>
<div class="line">cmake .. -DCMAKE_C_COMPILER=/usr/local/gcc-8.2/bin/gcc -DCMAKE_CXX_COMPILER=/usr/local/gcc-8.2/bin/g++</div>
<div class="line"> </div>
<div class="line"># Microsoft Visual Studio for Windows:</div>
<div class="line">cmake .. -G &quot;Visual Studio 16 2019&quot; -A x64</div>
<div class="line">cmake .. -G &quot;Visual Studio 16 2019&quot; -A Win32</div>
<div class="line">cmake .. -G &quot;Visual Studio 15 2017 Win64&quot;</div>
<div class="line"> </div>
<div class="line"># Xcode for macOS:</div>
<div class="line">cmake .. -G Xcode</div>
<div class="line"> </div>
<div class="line"># Xcode for iOS:</div>
<div class="line">cmake .. -G Xcode -DCMAKE_SYSTEM_NAME=iOS</div>
<div class="line"> </div>
<div class="line"># Xcode with XCTest</div>
<div class="line">cmake .. -G Xcode -DYYJSON_BUILD_TESTS=ON</div>
</div><!-- fragment --><h2><a class="anchor" id="use-cmake-to-generate-documentation"></a>
Use CMake to generate documentation</h2>
<p>This project uses <a href="https://www.doxygen.nl/">doxygen</a> to generate the documentation. Make sure <code>doxygen</code> is installed on your system before proceeding, it's best to use the version specified in <code>doc/Doxyfile.in</code>.</p>
<p>To build the documentation: </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DYYJSON_BUILD_DOC=ON</div>
<div class="line">cmake --build .</div>
</div><!-- fragment --><p>The generated HTML files will be located in <code>build/doxygen/html</code>.</p>
<p>You can also browse the pre-generated documentation online: <a href="https://ibireme.github.io/yyjson/doc/doxygen/html/">https://ibireme.github.io/yyjson/doc/doxygen/html/</a></p>
<h2><a class="anchor" id="testing-with-cmake-and-ctest"></a>
Testing With CMake and CTest</h2>
<p>Build and run all tests: </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DYYJSON_BUILD_TESTS=ON</div>
<div class="line">cmake --build .</div>
<div class="line">ctest --output-on-failure</div>
</div><!-- fragment --><p>Build and run tests with <a href="https://valgrind.org/">valgrind</a> memory checker, (make sure you have <code>valgrind</code> installed before proceeding): </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_VALGRIND=ON</div>
<div class="line">cmake --build .</div>
<div class="line">ctest --output-on-failure</div>
</div><!-- fragment --><p>Build and run tests with sanitizer (compiler should be <code>gcc</code> or <code>clang</code>): </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_SANITIZE=ON</div>
<div class="line">cmake --build .</div>
<div class="line">ctest --output-on-failure</div>
</div><!-- fragment --><p>Build and run code coverage with <code>gcc</code>: </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DCMAKE_BUILD_TYPE=Debug -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_COVERAGE=ON</div>
<div class="line">cmake --build . --config Debug</div>
<div class="line">ctest --output-on-failure</div>
<div class="line"> </div>
<div class="line">lcov -c -d ./CMakeFiles --include &quot;*/yyjson.*&quot; -o cov.info</div>
<div class="line">genhtml cov.info -o ./cov_report</div>
</div><!-- fragment --><p>Build and run code coverage with <code>clang</code>: </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DCMAKE_BUILD_TYPE=Debug -DYYJSON_BUILD_TESTS=ON -DYYJSON_ENABLE_COVERAGE=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++</div>
<div class="line">cmake --build . --config Debug</div>
<div class="line"> </div>
<div class="line">export LLVM_PROFILE_FILE=cov/profile-%p.profraw</div>
<div class="line">ctest --output-on-failure</div>
<div class="line"> </div>
<div class="line">ctest_files=$(grep -o &quot;test_\w\+&quot; CTestTestfile.cmake | uniq | tr &#39;\n&#39; &#39; &#39;)</div>
<div class="line">ctest_files=$(echo $ctest_files | sed &#39;s/  $//&#39; | sed &quot;s/ / -object /g&quot;)</div>
<div class="line">llvm-profdata merge -sparse cov/profile-*.profraw -o coverage.profdata</div>
<div class="line">llvm-cov show $ctest_files -instr-profile=coverage.profdata -format=html &gt; coverage.html</div>
</div><!-- fragment --><p>Build and run fuzz test with <a href="https://llvm.org/docs/LibFuzzer.html">LibFuzzer</a> (compiler should be <code>LLVM Clang</code>, while <code>Apple Clang</code> or <code>gcc</code> are not supported): </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DYYJSON_BUILD_FUZZER=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++</div>
<div class="line">cmake --build .</div>
<div class="line">./fuzzer -dict=fuzzer.dict ./corpus</div>
</div><!-- fragment --><h1><a class="anchor" id="compile-time-options"></a>
Compile-time Options</h1>
<p>This library provides some compile-time options that can be defined as 1 to disable specific features during compilation. For example, to disable the JSON writer: </p><div class="fragment"><div class="line">cmake -E make_directory build; cd build</div>
<div class="line">cmake .. -DYYJSON_DISABLE_WRITER=ON</div>
<div class="line">gcc -DYYJSON_DISABLE_WRITER=1 ...</div>
</div><!-- fragment --><h2><a class="anchor" id="yyjson_disable_reader"></a>
YYJSON_DISABLE_READER</h2>
<p>Define as 1 to disable JSON reader at compile-time.<br  />
 This disables functions with <code>read</code> in their name.<br  />
 Reduces binary size by about 60%.<br  />
 It is recommended when JSON parsing is not required.<br  />
</p>
<h2><a class="anchor" id="yyjson_disable_writer"></a>
YYJSON_DISABLE_WRITER</h2>
<p>Define as 1 to disable JSON writer at compile-time.<br  />
 This disables functions with <code>write</code> in their name.<br  />
 Reduces binary size by about 30%.<br  />
 It is recommended when JSON serialization is not required.<br  />
</p>
<h2><a class="anchor" id="yyjson_disable_incr_reader"></a>
YYJSON_DISABLE_INCR_READER</h2>
<p>Define as 1 to disable JSON incremental reader at compile-time.<br  />
 This disables functions with <code>incr</code> in their name.<br  />
 It is recommended when JSON incremental reader is not required.<br  />
</p>
<h2><a class="anchor" id="yyjson_disable_utils"></a>
YYJSON_DISABLE_UTILS</h2>
<p>Define as 1 to disable JSON Pointer, JSON Patch and JSON Merge Patch supports.<br  />
 This disables functions with <code>ptr</code> or <code>patch</code> in their name.<br  />
 It is recommended when these functions are not required.<br  />
</p>
<h2><a class="anchor" id="yyjson_disable_fast_fp_conv"></a>
YYJSON_DISABLE_FAST_FP_CONV</h2>
<p>Define as 1 to disable the fast floating-point number conversion in yyjson.<br  />
 Libc's <code>strtod/snprintf</code> will be used instead.<br  />
 This reduces binary size by about 30%, but significantly slows down the floating-point read/write speed.<br  />
 It is recommended when processing JSON with few floating-point numbers.<br  />
</p>
<h2><a class="anchor" id="yyjson_disable_non_standard"></a>
YYJSON_DISABLE_NON_STANDARD</h2>
<p>Define as 1 to disable non-standard JSON features support at compile-time:</p><ul>
<li>YYJSON_READ_ALLOW_INF_AND_NAN</li>
<li>YYJSON_READ_ALLOW_COMMENTS</li>
<li>YYJSON_READ_ALLOW_TRAILING_COMMAS</li>
<li>YYJSON_READ_ALLOW_INVALID_UNICODE</li>
<li>YYJSON_READ_ALLOW_BOM</li>
<li>YYJSON_WRITE_ALLOW_INF_AND_NAN</li>
<li>YYJSON_WRITE_ALLOW_INVALID_UNICODE</li>
</ul>
<p>This reduces binary size by about 10%, and slightly improves performance.<br  />
 It is recommended when not dealing with non-standard JSON.</p>
<h2><a class="anchor" id="yyjson_disable_utf8_validation"></a>
YYJSON_DISABLE_UTF8_VALIDATION</h2>
<p>Define as 1 to disable UTF-8 validation at compile-time.</p>
<p>Use this if all input strings are guaranteed to be valid UTF-8 (e.g. language-level String types are already validated).</p>
<p>Disabling UTF-8 validation improves performance for non-ASCII strings by about 3% to 7%.</p>
<p>Note: If this flag is enabled while passing illegal UTF-8 strings, the following errors may occur:</p><ul>
<li>Escaped characters may be ignored when parsing JSON strings.</li>
<li>Ending quotes may be ignored when parsing JSON strings, causing the string to merge with the next value.</li>
<li>When serializing with <code><a class="el" href="yyjson_8h.html#structyyjson__mut__val">yyjson_mut_val</a></code>, the string's end may be accessed out of bounds, potentially causing a segmentation fault.</li>
</ul>
<h2><a class="anchor" id="yyjson_exports"></a>
YYJSON_EXPORTS</h2>
<p>Define as 1 to export symbols when building the library as a Windows DLL.</p>
<h2><a class="anchor" id="yyjson_imports"></a>
YYJSON_IMPORTS</h2>
<p>Define as 1 to import symbols when using the library as a Windows DLL. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.13.2-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Documentation for <a href="https://github.com/ibireme/yyjson" target="_blank">yyjson</a>, generated by <a href="https://www.doxygen.org/index.html" target="_blank">doxygen</a> 1.13.2 </li>
  </ul>
</div>
</body>
</html>
